Custom widgets are a special subset of scripts that render graphical elements in certain parts of the application. These can be used to add new functionality to the Trilium application.

Preact with JSX vs. vanilla jQuery

In older versions of Trilium, custom widgets were exclusively written in a combination of jQuery with Trilium's internal widget architecture (e.g., BasicWidget, NoteContextAwareWidget).

Starting with v0.101.0, custom widgets can also be written in JSX using the Preact framework. Both legacy and Preact widgets have the same capabilities, with a single difference:

• Preact widgets are content-sized by default whereas legacy widgets need this.contentSized() applied in the constructor. For more information, see the corresponding section in Troubleshooting.

Wherever possible, widget examples will be both in the legacy and Preact format.

Creating a custom widget

The quickest way is Insert child note → Code → Widget in the Note tree contextual menu. It creates a JSX note with the #widget label and a minimal Preact widget to start from.

To set one up by hand instead:

1. Create a Code note.
2. Set the language to:
   1. JavaScript (frontend) for legacy widgets using jQuery.
   2. JSX for Preact widgets. You might need to go to Options → Code to enable the language first.
3. Apply the #widget label.

Getting started with a simple example

Let's start by creating a widget that shows a message near the content area. Follow the previous section to create a code note, and use the following content.

import { defineWidget } from "trilium:preact";

export default defineWidget({
    parent: "center-pane",
    render: () => <span>Center pane from Preact.</span>
});

class HelloCenterPane extends api.BasicWidget {

    constructor() {
        super();
        this.contentSized();
    }

    get parentWidget() { return "center-pane" }

    doRender() {
        this.$widget = $("<span>Center pane</span>");
    }
    
}

module.exports = new HelloCenterPane();

Refresh the application and the widget should appear underneath the content area.

Widget location (parent widget)

A widget can be placed in one of the following sections of the applications:

To position the widget somewhere else, just change the value passed to get parentWidget() for legacy widgets or the parent field for Preact. Do note that some positions such as note-detail-pane and right-pane have special requirements that need to be accounted for (see the table above).

Multiple widgets in a single note

A widget note usually returns one widget, but it can also return an array of them. This is useful when several widgets share code or state, since they can all live in the same note instead of being split across notes that need a shared module.

Each widget of the array is registered on its own, so they can have different parents and positions. A widget that is missing its parentWidget (or parent for Preact) is reported as an error without affecting the other widgets of the note.

import { defineWidget } from "trilium:preact";

export default [
    defineWidget({
        parent: "left-pane",
        render: () => <span>Left pane from Preact.</span>
    }),
    defineWidget({
        parent: "right-pane",
        render: () => <span>Right pane from Preact.</span>
    })
];

class TreeWidget extends api.BasicWidget {
    get parentWidget() { return "left-pane"; }
    doRender() { this.$widget = $("<span>Left pane</span>"); }
}

class SidebarWidget extends api.BasicWidget {
    get parentWidget() { return "right-pane"; }
    doRender() { this.$widget = $("<span>Right pane</span>"); }
}

module.exports = [ new TreeWidget(), new SidebarWidget() ];

Launch bar widgets

Launch bar widgets are similar to Custom widgets but are specific to the Launch Bar. See Launch Bar Widgets for more information.

Custom position

The position of a custom widget is defined via a position integer.

export default defineWidget({
    // [...]
    position: 10
});

class MyWidget extends api.BasicWidget {
	// [..
	get position() { return 10; }
}